最強のMarkdown編集環境を模索する

Markdownの編集環境は悩ましい問題です。このエントリでは現時点で私がたどり着いたMarkdown編集環境(IntelliJ IDEA、VSCode、Vimなど)を、その前提、要求事項とその対応状況ともに紹介します。

#Markdown

#設計

髙野将

2018.12.04

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

みなさん、Markdown書いてますか？

私が所属する事業開発部では、prismatixというサービスの開発をしています。そして、その仕様書などのドキュメントの多くがMarkdown形式で書かれています。そのため、私も日々Markdownを書いているのですが、その編集環境をできれば快適なものにしたいと思って試行錯誤しています。

本エントリでは、私が求める理想的なMarkdown編集環境に対し、現在どのような手段で実現しているか紹介します。

TL;DR;

現時点ではIntelliJ IDEAとそのプラグインが良い
VSCodeとその拡張も捨てがたい
Vimでもそれなりに行ける

Markdown編集環境に求めるもの

現在作成しているドキュメントには次のような特徴があります。

プロジェクトリポジトリにソースとドキュメントが同梱されている
ソースとドキュメントは不可分なものであり、一緒にバージョン管理されるべきです
MarkdownにPlantUMLが埋め込まれている
設計文書に必要なクラス図、状態遷移図、シーケンス図は、UMLをテキスト形式で書けるPlantUMLで表現しています
開発言語はJava
ドキュメントに直接関係するものではありませんが、編集環境を選ぶ際の視点の一つです

これらのことから、私がMarkdown編集環境に求めるものは、次のようなものです。

開発環境と共用
Markdownのハイライト
Markdownのプレビュー
PlantUMLのハイライト
PlantUMLのプレビュー
Vimキーバインド(これだけは好み)

上記の要求に対して、色々編集環境を試行錯誤してきました。その中で良さそうな3つを紹介します。

IntelliJ IDEA + Markdown support Plugin + PlantUML integration Plugin + IdeaVim Plugin

現在のメインの編集環境です。コードと一緒に扱うのに都合が良いのが一番の理由です。

ただ、色々不都合があったので設定で回避しています。

要求へのマッチ状況

○ 開発環境と共用
○ Markdownのハイライト
○ Markdownのプレビュー
× PlantUMLのハイライト
△ PlantUMLのプレビュー
○ Vimキーバインド

メリット

みんな大好きIntelliJ IDEAから出なくて良い
IdeaVimのVim再現度がそこそこ良い(日本語もある程度)
(公式には)IntelliJ IDEAはPlantUMLプレビューをサポートしている
Markdown - Help | IntelliJ IDEA

デメリット

Markdownプレビューがダークテーマでテーブルがフル幅になってしまう
Markdownプレビュー内でのPlantUMLプレビューが私の環境では動かない
- PlantUML integrationプラグインを使い、別窓でPlantUML部分のみプレビューすることで回避している
IdeaVimはq, :によるコマンド履歴をサポートしていないのでたまに面倒臭い

Markdownプレビューの見た目変更

Markdown supportプラグインはCSSで見た目をカスタマイズできるため、GitHubに近い好みの形にしています。

Before

After

CSS例

/*
背景色、文字色指定
*/
body {
  background-color: white;
  color: #24292e;
}
/*
テーブルの整形 
- 既定だとページ幅いっぱいになっていたのをやめる
- ヘッダーを見やすくする
*/
table {
  width: auto;
  border-collapse: collapse;
  border-spacing: 0;
  border-width: 1px;
}
td, th {
  min-width: 100px;
  background-color: #f9f9f9;
  border-color: #eeeeee;
}
th {
  font-weight: bold;
}
/*
コード
*/
pre, code {
  background-color: rgba(27,31,35,0.05);
  font-size: 85%;
  color: #24292e;
}
/*
引用
*/
blockquote {
  color: #6a737d;
}